home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.024 < prev    next >
Encoding:
Text File  |  1991-11-15  |  12.0 KB  |  297 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #24:         Apple IIgs Toolbox Reference Updates
  8.  
  9. Revised by:    Dave Lyons                                       December 1991
  10. Written by:    Rilla Reynolds, Matt Deatherage, Dave Lyons,
  11.                C.K. Haun & Eric Soldan                           October 1987
  12.  
  13. This Technical Note documents changes to the Apple IIgs Toolbox Reference 
  14. manuals.  Please contact Apple II Developer Technical Support at the address 
  15. listed in Apple II Technical Note #0 if you have additional corrections or 
  16. suggestions for any of the Apple IIgs Toolbox documentation.
  17.  
  18. Changes since July 1991:  Added corrections to Volume 1:  SetVector; 
  19. and Volume 3: Control Manager and Standard File.
  20. _____________________________________________________________________________
  21.  
  22. The current Apple IIgs Toolbox reference material is Apple IIgs Toolbox 
  23. Reference, volumes 1 to 3 as well as this Technical Note.  (The Apple IIgs 
  24. Toolbox Reference Update beta draft from APDA is obsolete and should not be 
  25. used.)
  26.  
  27. Corrections to Volume 1
  28.  
  29. FixAppleMenu Can Die With Error $0512
  30.  
  31. Fatal system error $0512 comes from FixAppleMenu (in the Desk Manager).  It 
  32. means that one of your installed New Desk Accessories does not have a 
  33. well-formed menu title string.  In particular, the required backslash (\) 
  34. character was not found (make sure bit seven is off).
  35.  
  36. DeleteMItem Operates on the Current Menu Bar
  37.  
  38. Page 13-37 says DeleteMItem removes the specified item from the current menu.  
  39. It means the item is removed from the current menu bar.
  40.  
  41. The List Manager Wants the Port Set Properly
  42.  
  43. The List Manager expects the current grafPort to be set properly before you 
  44. make most List Manager calls; drawing can occur in funny places if the 
  45. grafPort is not set properly before calls that draw (like SelectMember2).  
  46. Most List Manager calls, and many other toolbox calls, require that the 
  47. current grafPort be explicitly set.  Before you call List Manager routines 
  48. that draw, set the current port to your window with a SetPort call.  Remember 
  49. the note in Volume 2 under the NewWindow call--"Important:  NewWindow does 
  50. not set the current port, but many routines require that a current port 
  51. exist.  Use the QuickDraw II routine SetPort to set the current port."  Using 
  52. SetPort can prevent toolbox confusion and reduce your debugging time.
  53.  
  54. Error $0F02 from GetMItem
  55.  
  56. GetMItem returns error $0F02 if the specified menu item is not found.
  57.  
  58. SetVector Reference Numbers
  59.  
  60. On page 14-62, vector reference number $002C is listed as "Message 
  61. pointer vector."  $002C is actually the stack-based GS/OS call vector.  
  62. (The real message pointer vector is not accessible through GetVector and 
  63. SetVector.)
  64.  
  65. Getting a clean Mouse Mode from ReadMouse
  66.  
  67. On ROM 3 computers, the mouse mode byte returned from ReadMouse 
  68. sometimes has extra bits set in the high nibble.  Before feeding a 
  69. ReadMouse value to SetMouse, mask off all but the low nibble (AND 
  70. #$000F).
  71.  
  72. ReadAsciiTime Result Buffer
  73.  
  74. The description of ReadAsciiTime (in the Miscellaneous Tools) on page 14-16 
  75. should say the most significant bit (not byte) of each character is set to 
  76. one.
  77.  
  78. SystemEvent Is All Backwards
  79.  
  80. Although applications still should not call SystemEvent, we should note for 
  81. completeness that the input parameters listed in Volume 1 are exactly 
  82. backwards in the stack diagram.
  83.  
  84.  
  85. Corrections to Volume 2
  86.  
  87. QuickDraw Auxiliary Error Codes
  88.  
  89. Following are some error codes from QuickDraw Auxiliary that are not listed 
  90. in volume 2.
  91.  
  92.     $1210: picEmpty
  93.     $1211: picAlreadyOpen
  94.     $1212: pictureError
  95.  
  96.     $1221: badRect
  97.     $1222: badMode
  98.  
  99. FrameRgn Does Not Contribute to an Open Region
  100.  
  101. The description of the FrameRgn routine on page 16-105 in the Apple IIgs 
  102. Toolbox Reference, Volume 2 states that FrameRgn will contribute to a region 
  103. definition if a region is open when FrameRgn is called.  This is incorrect; 
  104. FrameRgn does not contribute to the region being defined.  To add a region to 
  105. another region, use XorRgn or UnionRgn.
  106.  
  107. Tool Locator, TLMountVolume
  108.  
  109. On page 24-21, the description of TLMountVolume does not bother to mention 
  110. that QuickDrawJII and Event Manager must be active.  If they are not, you 
  111. should use TLTextMountVolume instead.
  112.  
  113. Window Manager, "Draw Information Bar Routine"
  114.  
  115. On page 25-23, the code to clean up the stack is incorrect.  On the sta <14, 
  116. the comment "Works because stack and direct page are equal" is no longer 
  117. true--they were equal until the PLY two lines earlier.  One way to correct 
  118. the code is to replace sta <14 with sta 14,s and sta <12 with sta 12,s.
  119.  
  120. Window Manager, InvalRect
  121.  
  122. The description of InvalRect on page 25-80 claims that InvalRect modifies the 
  123. input rectangle; the rectangle is actually not modified.
  124.  
  125. Window Manager, SetZoomRect
  126.  
  127. The description of SetZoomRect on page 25-112 refers to fZoomed as bit 2 in 
  128. the window frame.  fZoomed is actually bit 1, with value $0002.
  129.  
  130. Appendix A, "Writing Your Own Tool Sets"
  131.  
  132. At the bottom of page A-8, "lda #$90" should read "lda #$8100" for version 
  133. 1.0 prototype.
  134.  
  135. On page A-10, the figure should show two RTL addresses (6 bytes) on the 
  136. stack.
  137.  
  138.  
  139. Corrections to Volume 3
  140.  
  141. Control Manager:  Menu Events
  142.  
  143. On page 28-15, note that a Menu Event is identified by the value wInSpecial 
  144. ($0019) in the what field of the task record.  The menu item ID is in the low 
  145. word of the wmTaskData field.
  146.  
  147. In the Draw routine for both extended and non-extended controls, the high 
  148. word of ctlParam (which was previously undefined) contains a flag which the 
  149. definition procedure can use to draw a normal or dimmed control.  The value 
  150. is $0000 normally, but it is $FFFF when the control is inactive (hilite value 
  151. equals $00FF), or when the control's state is tied to the window's state and 
  152. the window is inactive.
  153.  
  154. Control Manager:  Dimmed Custom Controls
  155.  
  156. In the Draw routine for both extended and non-extended controls, the 
  157. high word of ctlParam (which was previously undocumented) contains a 
  158. flag which the definition procedure can use to draw a normal or dimmed 
  159. control.  The value is $0000 normally, but it is $FFFF when the control 
  160. is inactive (hilite value equals $00FF), or when the control's state is 
  161. tied to the window's state and the window is inactive.
  162.  
  163. Control Manager:  Size Box Controls
  164.  
  165. The part code for an extended Size Box control is normally 10.  If the 
  166. fCallWindowMgr bit is set in ctlFlag, the part code is $80; and if the 
  167. size box is managed by a Text Edit control, the part code is $84.
  168.  
  169. When a Size Box control's fCallWindowMgr bit is set, the control needs 
  170. to pass a minimum window size to GrowWindow.  It gets this value from 
  171. its ctlData field, which you can get with GetCtlTitle and set with 
  172. SetCtlTitle (the low word is the minimum height, and the high word is 
  173. the minimum width).  A height of zero defaults to 50, and a width of 
  174. zero defaults to 130.
  175.  
  176. Desk Manager:  Errors from AddToRunQ and RemoveFromRunQ
  177.  
  178. The Desk Manager chapter, page 29-6, states no errors are possible for 
  179. AddToRunQ, but any errors from the Miscellaneous Tools routine AddToQueue are 
  180. returned unchanged.
  181.  
  182. Page 29-8 states no errors are possible from RemoveFromRunQ, but any errors 
  183. from DeleteFromQueue are returned unchanged.
  184.  
  185. Event Manager:  What SetAutoKeyLimit Really Does
  186.  
  187. Page 31-6 says that PostEvent will add up to the new auto-key limit number of 
  188. auto-key events before reverting to the rule that auto-key events are only to 
  189. be posted if the event queue is empty.  This is not quite right.  Actually, 
  190. the parameter to SetAutoKeyLimit is used in a size comparison on the event 
  191. queue--if there are newLimit or more events in the queue, auto-key events 
  192. will not be posted.  Volume 3 incorrectly states that up to newLimit auto-key 
  193. events will be posted; this is only true if you assume the event queue is 
  194. empty before the first auto-key event comes in.
  195.  
  196. List Manager
  197.  
  198. On page 35-9, the description of ResetMember2 does not point out an important 
  199. difference between ResetMember2 and NextMember2.  ResetMember2 deselects the 
  200. member found, but NextMember2 does not change the member's status.
  201.  
  202. On page 35-3, bit 5 of the memFlag field is defined--it makes an item 
  203. inactive.  To make use of this bit, you must also set bit 6 of the List 
  204. control's ctlFlag field; if you don't set this bit, the user will still be 
  205. able to select members using the mouse.
  206.  
  207. Memory Manager
  208.  
  209. If the Memory Manager detects a corrupted entry in the Out Of Memory Queue, 
  210. fatal system error $0209 occurs.
  211.  
  212. Menu Manager
  213.  
  214. On page 28-65, the description of the initialValue field is misleading.  
  215. Cross out the text "that is, its relative position within the array of items 
  216. for the menu."  initialValue is simply a menu item ID, not an offset into an 
  217. array.
  218.  
  219. Miscellaneous Tools:  Interrupt State Record Not Always Complete
  220.  
  221. The interrupt state record returned from GetInterruptState (and passed 
  222. to SetInterruptState) is not always completely filled in.  The Interrupt 
  223. Manager, in the interest of serving AppleTalk and serial interrupts as 
  224. rapidly as possible, does not take the time to save all the items in the 
  225. record until those timing-critical interrupt handlers have been called.  
  226. Some items are not saved at all unless the interrupt is determined to be 
  227. a BRK instruction.  Table 1 shows all items in the current interrupt 
  228. state record and when they become valid:
  229.  
  230.         Record variable         When valid
  231.                 irq_A             always
  232.                 irq_X             always
  233.                 irq_Y             always
  234.                 irq_S             after serial
  235.                 irq_D             always
  236.                 irq_P             only on break
  237.                 irq_DB            after serial
  238.                 irq_e             after serial
  239.                 irq_K             only on break
  240.                 irq_PC            only on break
  241.                 irq_state         after serial
  242.                 irq_shadow        always
  243.                 irq_mslot         after serial
  244.  
  245. Table 1--Validity of Interrupt Record
  246.  
  247.  
  248. Standard File
  249.  
  250. On page 48-39, the description of origNameRef reads "On output, this 
  251. string contains the string confirmed by the user, which may not be the 
  252. same length as the default value."  This sentence is confused; ignore 
  253. it.  The string is not changed at all; Standard File doesn't even know 
  254. how long the buffer is.
  255.  
  256.  
  257.  
  258. Tool Locator:  Notes on StartUpTools
  259.  
  260. StartUpTools in System Software 5.0.4 and earlier is intended to be used from 
  261. applications only, not from NDAs.
  262.  
  263. The order of the toolArray entries in the StartStop record is not important.  
  264. StartUpTools and ShutDownTools always start up and shut down tools in a 
  265. correct order.
  266.  
  267. StartUpTools in System Software 5.0.4 and earlier fails to open your 
  268. application's resource fork if the application's filename contains a slash 
  269. (/) or if the application directory path is longer than 64 characters.
  270.  
  271. For maximum compatibility, pass your application's master user ID with any 
  272. auxID to StartUpTools instead of allocating a new user ID.
  273.  
  274. Window Manager:NewWindow2 Parameters Override Template Even When You Pass NIL
  275.  
  276. The description of the NewWindow2 call on page 52-32 is in error.  The 
  277. description of the titlePtr, refCon, contentDrawPtr, and defProcPtr says, "To 
  278. prevent NewWindow2 from replacing the template values, supply NIL 
  279. pointers..."  This is only  true for the titlePtr parameter--if you pass NIL 
  280. for any of the other parameters then the value of that parameter in your 
  281. window record is also NIL, no matter what the template value was.  In other 
  282. words, if you have the value $99 stored in your template refCon field, and 
  283. you pass NIL for the refCon value in a NewWindow2 call, the value of the 
  284. refCon in the returned grafPortPtr is NIL.
  285.  
  286. Appendix E:  rTextForLETextBox2 Resources
  287.  
  288. Page E-68 of Volume 3 shows a length field at the beginning of an 
  289. rTextForLETextBox2 resource. This field is not actually present.  The length 
  290. is simply the size of the resource--it is not stored redundantly.
  291.  
  292.  
  293.  
  294. Further Reference
  295. _____________________________________________________________________________
  296.   o  Apple IIgs Toolbox Reference, Volumes 1-3
  297.